2.3 - Running an Example Bot

Now that your environment is configured, it's time for a "smoke test"—running a simple, pre-written bot to confirm that all the pieces connect and function correctly. The goal here is not to understand every line of code, but to verify your setup.

Execution Checklist

• Task 1: Create a Python file with the example bot code.
• Task 2: Run the script from your activated virtual environment.
• Task 3: Observe the StarCraft II client launching and the bot taking action.
• Task 4: Stop the script.

---

Step 1: Create the Bot Script

Create a new file in your project folder named worker_rush.py. Copy and paste the following code into it. This bot is designed to perform a "worker rush," sending all its workers to attack as soon as the game starts.

# worker_rush.py

# =================================================================
# IMPORTS: We are importing necessary components from the sc2 library
# =================================================================
from sc2.main import run_game  # The function that starts the game
from sc2 import maps          # The function for loading maps
from sc2.bot_ai import BotAI  # The base class for our bot
from sc2.player import Bot, Computer # Defines the players in the game
from sc2.data import Difficulty, Race # Defines race and game difficulty


class WorkerRushBot(BotAI):
    """A bot that executes a worker rush."""

    async def on_step(self, iteration: int):
        # The 'on_step' function is called for every single frame of the game.
        if iteration == 0:
            # The first frame is a great time to issue initial commands.
            print(f"Game started! Attacking enemy start location...")

            # Find the enemy's starting position.
            target = self.enemy_start_locations[0]

            # Select all workers and command them to attack the target.
            for worker in self.workers:
                worker.attack(target)


# This block of code is the entry point for running the bot.
if __name__ == "__main__":
    run_game(
        # 1. Choose the map to play on.
        maps.get("AbyssalReefLE"),
        # 2. Define the players.
        [
            Bot(Race.Terran, WorkerRushBot()),
            Computer(Race.Zerg, Difficulty.Easy),
        ],
        # 3. Run in real-time to watch the game.
        realtime=True,
    )

---

Step 2: How to Launch the Game

The run_game() function is the engine that launches your bot. It's helpful to understand its main parameters.

Parameter	Type	What It Does
map_name	str	Defines the name of the map the game will be played on.
players	list	A list of all participants. Can be a Bot, Computer, or Human.
realtime	bool	If True, the game runs at normal speed. If False, it runs as fast as possible, which is useful for testing but not for watching.

---

Step 3: Execution and Verification

Now, let's run the script. The following diagram shows what happens when you execute the command:

[ You in Terminal ]------------> [ python worker_rush.py ]
      (Execute)                            |
                                           | (Uses burnysc2 library)
                                           v
[ StarCraft II Game Client ] <--- [ Your Bot's Logic ]
      (Launches & Runs)                (Controls a player)

Execution To-Do List:

1. Activate your virtual environment if it isn't already. Your prompt should show (venv).
2. Run the script from your terminal:

   python worker_rush.py

3. Watch the screen. The StarCraft II client should launch automatically, load into the AbyssalReefLE map, and you will see your Terran SCVs immediately march across the map to attack the AI Zerg's base. The message "Game started!..." will appear in your terminal.
4. Stop the script. Once you are done watching, switch back to your terminal and press Ctrl+C to end the program.

If you saw the workers attack the enemy base, your installation is fully verified and working correctly. You have successfully run your first bot